home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / hardware / GIO_DRVR5.1 / gio_driver.txt < prev    next >
Text File  |  1994-08-01  |  45KB  |  1,333 lines
  1.  
  2. Writing Kernel-level GIO Device Drivers
  3.  
  4. This chapter provides in-depth information about drivers that interface to 
  5. the GIO bus. System configuration for GIO device drivers is described, and 
  6. several GIO-specific functions you should include in your device driver are 
  7. introduced. This chapter also describes several models for performing DMA 
  8. operations. Which model you choose for your device driver depends on the 
  9. capability of the device. The device may have hardware support for 
  10. scatter-gather or may require a software implementation of scatter-gather. 
  11. Memory-mapped, usr-level drivers for GIO devices are not supported. All 
  12. GIO drivers must be kernel-level drivers.
  13.  
  14. This chapter  contains the following sections:
  15.  
  16. o    "GIO-bus Architecture" 
  17.  
  18. o    "Determining GIO Device Addresses" 
  19.  
  20. o    "Including GIO Device Drivers in the Kernel" 
  21.  
  22. o    "Writing edtinit()" 
  23.  
  24. o    "GIO-Specific Functions" 
  25.  
  26. o    "GIO Interrupt Handler" 
  27.  
  28. o    "Programmed I/O (PIO)" 
  29.  
  30. o    "DMA Operations" 
  31.  
  32. o    "GIO Devices with Hardware-Supported Scatter-gather Capability" 
  33.  
  34. o    "DMA on GIO Devices with No Scatter-gather Capability" 
  35.  
  36. o    "Device Driver Example" 
  37.  
  38.  
  39.  
  40. GIO-bus Architecture
  41.  
  42. The GIO bus is a family of synchronous, multiplexed address-data buses for 
  43. connecting high-speed devices to main memory and CPU for entry-level 
  44. Silicon Graphics systems. The GIO bus has three varieties: GIO32, 
  45. GIO32-bis, and GIO64.
  46.  
  47. o    The GIO32 is a 32-bit, synchronous, multiplexed address-data bus that 
  48.     runs at speeds from 25 to 33 MHz. This bus is found on R3000-based 
  49.     Indigos.
  50.  
  51. o    The GIO32-bis is a cross between GIO32 and GIO64. It could be 
  52.     considered a 32-bit version of the non-pipelined GIO64 bus or a GIO32 
  53.     bus with pipelined control signals. This bus is found on R4000-based 
  54.     Indigo and Indy workstations.
  55.  
  56. o    The GIO64 bus is a 64-bit, synchronous, multiplexed address-data bus 
  57.     that can run at speeds up to 33 MHz. It supports both 32- and 64-bit 
  58.     GIO64 devices. GIO64 has two slightly different varieties: 
  59.     non-pipelined for internal system memory, and pipelined for graphics 
  60.     and pipelined GIO64 slot devices. This bus is implemented in the 
  61.     Indigo2 platform.
  62.  
  63. The members of the GIO-bus family are all very similar. However, the GIO32 
  64. and GIO64 are not compatible. A GIO32 device does not work in a GIO64 
  65. slot. However, a GIO32-bis device does fit in either a GIO32 or GIO32-bis 
  66. option slot. It is possible to design a board that functions in machines with 
  67. either a GIO32 or GIO32-bis bus.
  68.  
  69. The form factor and bus protocol depend on the specific platform in which 
  70. the device is installed. GIO32 and GIO32-bis devices can be either single or 
  71. double-wide (i.e., taking one or both board slots), while GIO64 boards are 
  72. the size of an EISA board. Slots in the Indigo2 can accept either an EISA 
  73. board or a GIO64 board. These two types of boards share common board 
  74. dimensions but have different connectors for attaching to their respective 
  75. buses.
  76.  
  77. The GIO Bus Specification contains more detailed information about the 
  78. various types of GIO buses, both from an electrical and mechanical point of 
  79. view.
  80.  
  81.  
  82.  
  83. Determining GIO Device Addresses
  84.  
  85. Each GIO device has a range of GIO-bus addresses to which it responds. 
  86. These addresses correspond to device registers or on-board memory, 
  87. depending on the GIO device. GIO-bus addresses cannot be mapped into 
  88. user address space. GIO devices can be classified as 32 bit or 64 bit. Unlike 
  89. VME, where the class of device determines the address range, each GIO 
  90. devices responds to the same address range.
  91.  
  92. The address range for GIO-bus devices is determined by the Slot Number of 
  93. the device. The hardware must be designed to determine the slot the device 
  94. is in and make the appropriate adjustments to respond to that slot's address 
  95. range.
  96.  
  97. GIO-bus devices use only one interrupt level - interrupt 1. Interrupts 0 and 
  98. 2 are used by the graphics system and may not be used by GIO-bus devices.
  99.  
  100. Since one interrupt serves multiple GIO devices, the interrupt routine in 
  101. each driver must be able to deal with the various interrupt situations:
  102.  
  103. o    The interrupt is for the board.
  104.  
  105. o    The interrupt is for some other GIO device.
  106.  
  107. o    There is no interrupt pending.
  108.  
  109.  
  110.  
  111. Including GIO Device Drivers in the Kernel
  112.  
  113. Chapter 2, "Writing a Device Driver",. provides general information on 
  114. adding a driver to the kernel. This section describes specifics concerning 
  115. GIO drivers. To add a new kernel-level GIO device driver, you must do the 
  116. following:
  117.  
  118. o    Create a system file
  119.  
  120. o    Create a master file
  121.  
  122. o    Create the boot file
  123.  
  124. For SCSI drivers, you use the INCLUDE directive, which unconditionally 
  125. adds the module to the kernel. Because lboot() can probe for GIO devices, 
  126. lboot() can conditionally include a GIO device driver into the kernel.
  127.  
  128. Creating a system file
  129.  
  130. This file resides in the var/sysgen/system directory and contains the 
  131. instructions that lboot will use to add the software module to the kernel. This 
  132. normally consists of the VECTOR directive. In fact, the file may consist of 
  133. one or more VECTOR directives. The file name must end in .sm for lboot to 
  134. recognize and include the software module. Typically the file name is the 
  135. software module's name with the .sm suffix. For example, gbd.sm.
  136.  
  137. If the current system contains the GIO device, lboot() includes the driver; 
  138. otherwise, it saves memory by leaving it out. Use the VECTOR directive to 
  139. include a GIO device conditionally. In addition to the module name, the 
  140. VECTOR directive requires that you fill out these fields:
  141.  
  142. vector    The interrupt vector value, as described previously. The 
  143.         interrupt vector for GIO devices is set using the 
  144.         setgiovector() function. Therefore, the vector in the 
  145.         VECTOR statement should always be 0x0 for GIO devices.
  146.  
  147. unit    The device number that differentiates between more than 
  148.         one device of the same type. This value is related to VME 
  149.         style devices. For GIO devices, this value can be anything, 
  150.         but for consistency, make it 0.
  151.  
  152. base    The device address(es) on the GIO bus. This is determined 
  153.         by the slot in which the board is installed. This is a K1 
  154.         address (see kvtophys(3K) man page).
  155.  
  156. base2, base3    Additional addresses passed to driver edtinit() routine 
  157.         via edt structure. These are K1 addresses (see the  
  158.         kvtophys(3K) man page).
  159.  
  160. exprobe       The address read when lboot() determines the existence of 
  161.         the device. This address is often the same as the base 
  162.         address. If you do not specify a probe address, the module 
  163.         is automatically included in the kernel. For GIO bus devices 
  164.         the exprobe() call is used in place of the probe call. The 
  165.         fields used for this call are as follows:
  166.  
  167.         operation         read ("r") or write ("w")
  168.  
  169.         address             address to probe
  170.  
  171.         # of bytes          number of bytes to read or write
  172.  
  173.         value             expected response value 
  174.                          (the GIO ID number)
  175.  
  176.         mask             mask to apply to value
  177.  
  178. Creating a master file
  179.  
  180. This file resides in the /var/sysgen/master.d directory. It contains the 
  181. information that lboot uses to create the device switch table as well as 
  182. indicating dependencies with other kernel modules. The name of the master 
  183. file should be the same as the software module. This file also contains the 
  184. prefix used in building the driver entry points. 
  185.  
  186. The FLAG field of the master file should at least include the character device 
  187. flag c. 
  188.  
  189. Creating a boot file
  190.  
  191. This file must reside in the /var/sysgen/boot directory. This file is the 
  192. successfully compiled driver object file. The name of the boot file must end 
  193. with the ".o" suffix. 
  194.  
  195. The GBD Example
  196.  
  197. As an example, suppose you want to add a mythical GIO device driver to the 
  198. kernel of an R4000 Indigo (IP20). You must copy the driver object file gbd.o 
  199. to /usr/sysgen/IP20boot, create a master file (as shown below), and create a 
  200. system file with the following VECTOR directive:
  201.  
  202. VECTOR: module=gbd vector=0x0 unit=0 base=0xBF400000  
  203. base2=0xBF410000 exprobe=(r,0xBF400000,4,0x75,0xff) 
  204.  
  205. Note that the interrupt vector (vector=), the base addresses, and the probe 
  206. address must all be specified in hexadecimal format. The base address and 
  207. the address in the exprobe must agree. In the above example, lboot() reads 
  208. four bytes at probe address, 0xBF400000, to determine whether the device is 
  209. present in slot 0. In this example, base2 is used to point to the location of 
  210. onboard memory.
  211.  
  212. In actual use, it is advisable to add a second VECTOR line to the system file. 
  213. This should perform a probe of the other GIO slot. If only the line above had 
  214. been used and the GIO device was physically placed in slot 1 rather than slot 
  215. 0 as specified in the VECTOR line, the probe would fail and the driver would 
  216. not have been included in the kernel. Using this situation as an example, the 
  217. following line should be added to the system file:
  218.  
  219. VECTOR: module=gbd vector=0x0 unit=0 base=0xBF600000  
  220. base2=0xBF610000 exprobe=(r,0xBF600000,4,0x75,0xff) 
  221.  
  222. This ensures that a GIO device placed in either slot will be recognized.
  223.  
  224. After examining /usr/include/sys/major.h and looking for potential major 
  225. device number conflicts in other device files in the /var/sysgen/master.d 
  226. directory, you determine that major device number 51 is available and can 
  227. be used for this device. You then create a master file, gbd, and enter:
  228.  
  229. *FLAG     PREFIX    SOFT      #DEV       DEPENDENCIES
  230.  
  231.  c        gbd       51        -
  232.  
  233.  
  234.  
  235. Writing edtinit()
  236.  
  237. If you use the VECTOR directive to configure a driver into the kernel, your 
  238. driver can use a function of the form drvedtinit(), where drv is the driver 
  239. prefix. If your device driver object module includes a drvedtinit() 
  240. function, the system executes the drvedtinit() function when the system 
  241. boots. In general, you can use your drvedtinit() function to perform any 
  242. device driver initialization you want.
  243.  
  244. Synopsis:
  245.  
  246. drvedtinit(e)
  247.  
  248. struct edt *e
  249.  
  250. {
  251.    your code here
  252. }
  253.  
  254. When the system calls your drvedtinit() function, it hands the function a 
  255. pointer to a structure of type edt. (This structure type is defined in the 
  256. sys/edt.h header file.) The definition of the edt type structure is:
  257.  
  258. #define NBASE 3
  259.  
  260. typedef unsigned long iopaddr_t;
  261. typedef struct iospace {
  262.     unchar    ios_type;     /* io space type on adapter */
  263.     iopaddr_t ios_iopaddr;  /* io space base address */
  264.     ulong     ios_size;
  265.     caddr_t   ios_vaddr;    /* kernel virtual address */
  266. } iospace_t;
  267.  
  268. typedef struct edt {
  269.     uint_t    e_bus_type;   /* vme, scsi, eisa... */
  270.     unchar    v_cpuintr;    /* cpu to send intr to */
  271.     uint_t    e_adap;       /* adapter */
  272.     uint_t    e_ctlr;       /* controller identifier */
  273.     void*     e_bus_info;   /* bus dependent info */
  274.     int       (*e_init)(struct edt *);/* device init
  275.                                     /run-time probe*/
  276.     iospace_t e_space[NBASE];
  277. } edt_t;
  278.  
  279. #define e_base          e_space[0].ios_vaddr
  280. #define e_base2         e_space[1].ios_vaddr
  281. #define e_base3         e_space[2].ios_vaddr
  282. #define e_iobase        e_space[0].ios_iopaddr
  283. #define e_iobase2       e_space[1].ios_iopaddr
  284. #define e_iobase3       e_space[2].ios_iopaddr
  285.  
  286.  
  287.  
  288. The e_bus_type should be ADAP_GIO (this is defined in edt.h). The e_ctrl, 
  289. v_cpuintr, and ios_type values should be 0. The (*e_init)() member is of no 
  290. interest to your drvedtinit() function. Your driver uses the e_base, e_base2, 
  291. and e_base3 members:
  292.  
  293. e_base, e_base2, e_base3    
  294.             These members give your driver the base addresses as 
  295.             specified in the VECTOR line. Each is assigned as an 
  296.             unsigned long data type.
  297.  
  298. Note:  Although lboot() knows not to include in the kernel any GIO 
  299.         device driver for a device that is not present, it is a good 
  300.         idea for your drvedtinit() function to probe for its device 
  301.         with badaddr_val(). This allows you to write a driver that 
  302.         is prepared if the device has been removed from the system 
  303.         after the kernel has been built or when the kernel runs on 
  304.         another system.
  305.  
  306. Continuing with this mythical GIO device driver example, its 
  307. drvedtinit() function could look like:
  308.  
  309. /* equipped device table initialization function. The edt
  310.  * structure is defined in edt.h.
  311.  */
  312. void
  313. gbdedtinit(struct edt *e)
  314. {
  315.    int slot, val;
  316.  
  317.    /* Check to see if the device is present */
  318.    if(badaddr_val(e->e_base, sizeof(int), &val) ||
  319.          (val && GBD_MASK) != GBD_BOARD_ID) {
  320.       if (showconfig)
  321.          cmn_err (CE_CONT,
  322.             "gbdedtinit: board not installed.");
  323.          return;
  324.    }
  325.  
  326.  
  327.    /* figure out slot from base on VECTOR line in
  328.    * system file */
  329.    if(e->e_base == (caddr_t)0xBF400000)
  330.       slot = GIO_SLOT_0;
  331.    else if(e->e_base == (caddr_t)0xBF600000)
  332.       slot = GIO_SLOT_1;
  333.    else {
  334.       cmn_err (CE_NOTE,
  335.       "ERROR from edtinit: Bad base address %x\n", e->e_base);
  336.       return;
  337.    }
  338.  
  339. #if IP12      /* For Indigo R3000, set up board as a
  340.                 * realtime bus master
  341.                 */
  342.  
  343.    setgioconfig(slot,0);
  344.  
  345. #endif
  346.  
  347. #if IP20      /* For Indigo R4000, set up board as a
  348.                 * realtime bus master
  349.                 */
  350.  
  351.    setgioconfig(slot,GIO64_ARB_EXP0_RT | GIO64_ARB_EXP0_MST);
  352.  
  353. #endif
  354.  
  355.  
  356.  
  357. #if IP22      /* For Indigo2, set up board as a pipelined,
  358.                 * realtime bus master
  359.                 */
  360.  
  361.    setgioconfig(slot,GIO64_ARB_EXP0_RT | GIO64_ARB_EXP0_MST) ;
  362.  
  363. #endif
  364.  
  365.    /* Save the device addresses, because
  366.     * they won't be available later.
  367.     */
  368.  
  369.    gbd_device[slot == GIO_SLOT_0 ? 0 : 1] =
  370.             (struct gbd_device *)e->e_base;
  371.    gbd_memory[slot == GIO_SLOT_0 ? 0 : 1] =
  372.             (char *)e->e_base2;
  373.    setgiovector(GIO_INTERRUPT_1,slot,gbdintr,0);
  374. }
  375.  
  376. GIO-Specific Functions
  377.  
  378. The GIO-specific support functions setgiovector(), setgioconfig(), 
  379. and splgio(n) must be included in the init() or edtinit() section of any 
  380. GIO driver.
  381.  
  382. Setgiovector
  383.  
  384. The setgiovector() function registers an interrupt service function for a 
  385. GIO-bus device interrupt with the kernel's interrupt dispatcher.
  386.  
  387. Synopsis:
  388.  
  389. setgiovector(int level,int slot,vo id (*func)(int),int arg)
  390.  
  391. Arguments:
  392.  
  393. level    Specifies which interrupt is used by the device. For GIO 
  394.         boards, this should always be GIO_INTERRUPT_1 since 
  395.         GIO_INTERRUPT_0 and GIO_INTERRUPT_2 are used by 
  396.         the graphics system.
  397.  
  398. slot    Specifies which physical slot the GIO-bus board is plugged 
  399.         into and should be either GIO_SLOT_0 or GIO_SLOT_1.
  400.  
  401.  func    Pointer to the interrupt service routine that will get called 
  402.         when the associated interrupt occurs. Note that func may be 
  403.         called even when there is no pending interrupt from the 
  404.         particular slot specified, in which case it should simply 
  405.         return. The interrupt handler therefore needs to be able to 
  406.         determine when its device is actually interrupting, and 
  407.         when it is not, in a timely, nondestructive manner.
  408.  
  409. arg        Passed to the interrupt service routine when it is called and 
  410.         may contain any value. The interrupt service routine will be 
  411.         called with the processor interrupt mask set to disable 
  412.         further interrupts from the device.
  413.  
  414. Splgio0, Splgio1, Splgio2
  415.  
  416. These functions set the processor interrupt mask to block GIO-bus 
  417. interrupts.
  418.  
  419. long splgio0();
  420.  
  421. long splgio1();
  422.  
  423. long splgio2();
  424.  
  425. Setgioconfig
  426.  
  427. setgioconfig (2K) sets up the GIO-bus arbitration mode for the GIO slot 
  428. specified by the slot parameter. The arbitration mode is specified in the flags 
  429. parameter as a bit-wise or of the flags documented below.
  430.  
  431. Synopsis:
  432.  
  433. setgioconfig(int slot, int flags)
  434.  
  435. For R3000-based machines using the GIO32 bus, these defines are found in 
  436. /usr/include/sys/IP12.h:
  437.  
  438. GIO_CONFIG_LONG                 Configure board as a long burst device; 
  439.                              otherwise it will be a real-time device.
  440.  
  441. GIO_CONFIG_SLAVE             Configure board as a bus slave; otherwise it 
  442.                              will be a bus master.
  443.  
  444. For R4000-based machines using the GIO32-bis or GIO64 bus, these defines 
  445. are found in /usr/include/sys/mc.h:
  446.  
  447. GIO64_ARB_EXP0_SIZE_64         Configure slot for 64 -bit transfers; otherwise 
  448.                              transfers will be 32-bit. For Indigo, this must 
  449.                              not be set.
  450.  
  451. GIO64_ARB_EXP0_RT             Configure slot as a real-time device; 
  452.                              otherwise it will be a long burst device.
  453.  
  454. GIO64_ARB_EXP0_MST             Configure slot as a bus master; otherwise it 
  455.                              will be a slave.
  456.  
  457. GIO64_ARB_EXP0_PIPED         Configure slot as a pipelined device, 
  458.                              otherwise it will be a non-pipelined device. 
  459.                              For Indigo, this must not be set. For Indigo2, 
  460.                              this must be set.
  461.  
  462. On R4000-based Indigos and Indigo2s, setgioconfig() uses the slot 
  463. argument to determine the location of boards.
  464.  
  465.  
  466.  
  467. GIO Interrupt Handler
  468.  
  469. Your driver module should contain an interrupt routine. The name of this 
  470. routine does not need to be drvintr(), since GIO uses setgiovector() to 
  471. register interrupt routines. When the device generates an interrupt, the 
  472. general GIO interrupt handler calls your driver's interrupt routine. When 
  473. the GIO interrupt handler calls your interrupt routine, it passes it the unit 
  474. number for the device. Within your interrupt routine, you should set flags to 
  475. indicate the state of the transfer, and wake up sleeping processes (if any) 
  476. waiting on the transfer to complete. Usually, the interrupt routine calls 
  477. iodone() to indicate that a block type I/O transfer for the buffer is complete.
  478.  
  479. Caution:  Interrupt routines must not try to sleep themselves by calling 
  480. iowait(), sleep(), psema(), or delay() kernel calls. Neither should they 
  481. try to access the per-process global variables in the u type structure directly. 
  482. The u type structure they can access may not be that of the process that made 
  483. the I/O request.
  484.  
  485. Programmed I/O (PIO)
  486.  
  487. When transferring large amounts of data, your device driver should use 
  488. direct memory access (DMA). Using DMA, your driver can program a few 
  489. registers, return, and put itself to sleep while it awaits an interrupt that 
  490. indicates the transfer is complete. This frees up the processor for use by 
  491. other processes.
  492.  
  493. However, sometimes you must write a driver for a device that does not 
  494. support DMA. In addition, even if the device does support DMA, you may 
  495. not want to use DMA to transfer amounts of data so small that the overhead 
  496. of DMA is not warranted.
  497.  
  498. In these cases, the host processor usually copies the data from the user space 
  499. to on-board memory. Your driver can then program the device registers to 
  500. notify the device that the memory is ready. The device controller can then 
  501. copy the data from its on-board memory to the peripheral (for example, a 
  502. printer or disk).
  503.  
  504. Listed below is part of a mythical GIO device driver for a printer controller 
  505. that does not support DMA. To print data from the user, the driver copies a 
  506. number of bytes (as specified by uio_resid) from the uio_iov array to an 
  507. onboard memory buffer of size GBD_MEMSIZE. Following the copy of each 
  508. chunk, the driver programs the device registers to indicate the size of valid 
  509. data in the memory and to tell the controller to start the printing.
  510.  
  511. Note that unlike previous versions of IRIX where direct access of the user 
  512. structure, u, was permitted, in IRIX 5.1 this is not allowed. Access to user 
  513. data is done only through the uio structure. For example, note that the field 
  514. u.u_count is not found in this driver, references are made to the uio_resid 
  515. field only.
  516.  
  517. The driver then sleeps, waiting for an interrupt to indicate that the printing 
  518. is complete and that the on-board memory buffer is available again. To 
  519. prevent a race condition in which the interrupt responds before the calling 
  520. process can sleep, the driver uses the splx(D3X) routine.
  521.  
  522. /* device write routine entry point (for character devices) 
  523.  */
  524. int
  525. gbdwrite(dev_t dev, uio_t *uio)
  526. {
  527.    int unit = geteminor(dev)&1;
  528.    int size, err=0, s;
  529.  
  530.    /* while there is data to transfer */
  531.    while((size=uio->uio_resid) > 0) {
  532.  
  533.       /* Transfer no more than GBD_MEMSIZE bytes
  534.        * to the device */
  535.       size = size < GBD_MEMSIZE ? size : GBD_MEMSIZE;
  536.  
  537.       /* decrements count and updates uio fields, and copies 
  538.        * data 
  539.           */
  540.       if(err=uiomove(gbd_memory[unit], size, UIO_WRITE, uio))
  541.          break;
  542.  
  543.       /* prevent interrupts until we sleep */
  544.       s = splgio1();
  545.  
  546.       /* Transfer is complete; start output */
  547.       gbd_device[unit]->count = size;
  548.       gbd_device[unit]->command = GBD_GO;
  549.       gbd_state[unit] = GBD_SLEEPING;
  550.       while (gbd_state[unit] != GBD_DONE) {
  551.          sleep(&gbd_state[unit], PRIBIO);
  552.       }
  553.       /* restore the process level after waking up */
  554.       splx(s);
  555.    }
  556.    return err;
  557. }
  558.  
  559. The driver's use of the volatile declaration informs the optimizer that this 
  560. register points to a hardware value that may change. Otherwise, the 
  561. optimizer may determine that one write to gbd_device->command is sufficient.
  562.  
  563. Note:  If your driver uses the sleep() and wakeup() kernel routines to 
  564.         sleep and awaken, it is a good idea for the drvintr() to verify 
  565.         that the actual event has occurred before actually awakening the 
  566.         sleeping process. (See sleep() for details on the sleep/wakeup 
  567.         process synchronization mechanism.) If your driver uses the 
  568.         iowait()/iodone() routines or the psema()/vsema() routines to 
  569.         sleep and awaken, you need not worry about its awakening by 
  570.         accident. However, the routines psema() and vsema(), are specific 
  571.         to IRIX and are probably not supported on other operating systems.
  572.  
  573. The uiomove() kernel routine is a useful procedure to call in these situations 
  574. because it automatically updates the fields in the uio structure and uses 
  575. copyout() (or copyin()) to check for invalid user addresses. Recall that 
  576. uio_resid must be left with the number of bytes left untransferred.
  577.  
  578.  
  579.  
  580. DMA Operations
  581.  
  582. As indicated in "Programmed I/O (PIO)," you should use DMA when the 
  583. device supports it. In its simplest form, DMA is easy to use: your driver gives 
  584. the device the physical memory address, and the transaction begins. Your 
  585. driver can then put itself to sleep while it waits for the transfer to complete, 
  586. thus freeing the processor for other tasks. When the transfer is complete, the 
  587. device interrupts the processor. On most systems, when large amounts of 
  588. data are involved, DMA devices obtain higher overall throughput than 
  589. devices that do only PIO.
  590.  
  591. DMA operations are categorized as a DMA read or a DMA write. DMA 
  592. operations that transfer from memory to device, and hence read memory, are 
  593. DMA reads. DMA operations that transfer from device to memory are DMA 
  594. writes. Thus, the point of view is that of memory. A disk read results in a 
  595. DMA write, and a disk write results in a DMA read.
  596.  
  597. There are some cache considerations for drivers using DMA. The cache 
  598. architecture of the machine dictates the appropriate cache operations. 
  599. Write-back caches require that data be written back from cache to memory 
  600. before a DMA read, whereas both write-back and write through caches 
  601. require the cache to be invalidated before data from a DMA write is used. See 
  602. "Data Cache Write-Back and Invalidation" in Appendix A and 
  603. dki_dcache_wbinval(D3X) for a discussion of these issues.
  604.  
  605. Another concern for driver writers is that DMA buffers may require 
  606. cache-line alignment. If a driver allocates a buffer for DMA, it should use the 
  607. kmem_alloc(D3X) function, using the KM_CACHEALIGN flag.
  608.  
  609. The interrupt service routine then calls your drvintr routine. Your 
  610. drvintr routine can check that the transfer is complete (if necessary), set 
  611. flags indicating the status of the transfer, and then awaken the sleeping 
  612. process.
  613.  
  614. The GIO bus does not provide any address mapping registers. Any DMA 
  615. operation that requires scatter-gather must be supported by GIO board 
  616. hardware or a software implementation of scatter-gather.
  617.  
  618. GIO Devices with Hardware-Supported Scatter-gather Capability
  619.  
  620. Chapter 2, "Writing a Device Driver," tells you to use the physio() kernel 
  621. routine to fault in and lock the physical pages corresponding to the user's 
  622. buffer. physio() also remaps these physical pages to a kernel virtual address 
  623. that remains constant even when the user's virtual addresses are no longer 
  624. mapped.
  625.  
  626. Internally, physio() allocates a structure of type buf if you pass a NULL 
  627. pointer. (physio() uses this structure to embody the transfer information.) 
  628. physio() then calls your drvstrategy() routine and passes it a pointer to 
  629. the buf type structure that it has allocated and primed. Your drvstrategy() 
  630. routine should then loop through each page, starting at the kernel virtual 
  631. address, and load each device scatter-gather register in turn with the 
  632. corresponding physical address. Use the kvtophys() routine to convert a 
  633. kernel virtual address to a physical address.
  634.  
  635. For example, suppose the mythical device is now a GIO device that has 
  636. hardware-supporting scatter-gather. The scatter-gather registers for the 
  637. device are simply a table of integers that store the physical pages 
  638. corresponding to the current transfer. To start the transfer, the driver gives 
  639. the device the beginning byte offset, byte count, and transfer direction. The 
  640. code is:
  641.  
  642. /* Actual device setup for DMA, etc., if your board has
  643.  * hardware scatter-gather DMA support.
  644.  * Called from the gbdwrite() routine via physio().
  645.  */
  646. void
  647. gbd_strategy(struct buf *bp)
  648. {
  649.    int unit = geteminor(bp->b_dev)&1;
  650.    int npages;
  651.    volatile unsigned *sgregisters;
  652.    int i, v_addr;
  653.  
  654.    /* Get address of the scatter-gather registers */
  655.     *sgregisters = gbd_device[unit]->sgregisters;
  656.  
  657.    /* Get the kernel virtual address of the data; note
  658.    * b_dmaaddr may be NULL if the BP_ISMAPPED(bp) macro
  659.    * indicates false; in that case, the field bp->b_pages
  660.    * is a pointer to a linked list of pfdat structure
  661.    * pointers; that saves creating a virtual mapping and
  662.    * then decoding that mapping back to physical addresses.
  663.    * BP_ISMAPPED will never be false for character devices,
  664.    * only block devices.
  665.    */
  666.  
  667.    if(!BP_ISMAPPED(bp)) {
  668.       cmn_err(CE_WARN,
  669.          "gbd driver can't handle unmapped buffers");
  670.       bp->b_flags |= B_ERROR;
  671.       iodone(bp);
  672.       return;
  673.    }
  674.  
  675.    v_addr = bp->b_dmaaddr;
  676.  
  677.    /* Compute number of pages received.
  678.    * The dma_len field provides the number of pages to
  679.    * map. Note that this may be larger than the actual
  680.    * number of bytes involved in the transfer. This is
  681.    * because the transfer may cross page boundaries,
  682.    * requiring an extra page to be mapped. Limit to
  683.    * number of scatter-gather registers on board.
  684.    * Note that this sample driver doesn't handle the
  685.    * case of requests > than # of registers!
  686.    */
  687.    npages = numpages (v_addr, bp->b_dmalen);
  688.    /*
  689.    * Provide the beginning byte offset and count to the
  690.    * device.
  691.    */
  692.  
  693.    gbd_device[unit]->offset =
  694.          (unsigned int)bp->b_dmaaddr & (NBPC-1);
  695.    if(npages > GBD_NUM_DMA_PGS) {
  696.       npages = GBD_NUM_DMA_PGS;
  697.       cmn_err(CE_WARN,
  698.       "request too large, only %d pages max", npages);
  699.       if(gbd_device[unit]->offset)
  700.          gbd_device[unit]->count = NBPC -
  701.          gbd_device[unit]->offset + (npages-1)*NBPC;
  702.       else
  703.          gbd_device[unit]->count = npages*NBPC;
  704.       bp->b_resid = bp->b_count - gbd_device[unit]->count;
  705.    }
  706.    else
  707.       gbd_device[unit]->count = bp->b_count;
  708.  
  709.    /* Translate the virtual address of each page to a
  710.    * physical page number and load it into the next
  711.    * scatter-gather register.  The btoct(D3X) macro
  712.    * converts the byte value to a page value after
  713.    * rounding down the byte value to a full page.
  714.    */
  715.    for (i = 0; i < npages; i++) {
  716.       *sgregisters++ = btoct(kvtophys(v_addr));
  717.  
  718.       /* Get the next virtual address to translate.
  719.       * (NBPC is a symbolic constant for the page
  720.       * size in bytes)
  721.       */
  722.  
  723.       v_addr += NBPC;
  724.    }
  725.  
  726.    if ((bp->b_flags & B_READ) == 0)
  727.       gbd_device[unit]->direction = GBD_WRITE;
  728.    else
  729.       gbd_device[unit]->direction = GBD_READ;
  730.    gbd_device[unit]->command = GBD_GO;   /* start DMA */
  731.  
  732.    /* and return; upper layers of kernel wait for iodone(bp) */
  733. }
  734.  
  735. DMA on GIO Devices with No Scatter-gather Capability
  736.  
  737. If your device does not provide any scatter-gather capability, your driver 
  738. must break up a data transfer so that no transfer crosses a page boundary. 
  739. The IRIX operating system provides a utility, sgset(), that simulates 
  740. scatter-gather registers in software. (See the IRIX Device Driver Reference 
  741. Pages for details on this routine.) Your driver can use this facility to perform 
  742. the virtual-to-physical mapping up front. Or, as the example below shows, 
  743. your driver can do this mapping following the transfer of each page:
  744.  
  745. /* Actual device setup for DMA, etc., if your board
  746.  * does NOT have hardware scatter-gather DMA support.
  747.  * Called from the gbdwrite() routine via physio().
  748.  */
  749. void
  750. gbd_strategy(struct buf *bp)
  751. {
  752.    int unit = geteminor(bp->b_dev)&1;
  753.    /* any checking for initial state here. */
  754.  
  755.    /* Get the kernel virtual address of the data; note
  756.    * b_dmaaddr may be NULL if the BP_ISMAPPED(bp) macro
  757.    * indicates false; in that case, the field bp->b_pages
  758.    * is a pointer to a linked list of pfdat structure
  759.    * pointers; that saves creating a virtual mapping and
  760.    * then decoding that mapping back to physical addresses.
  761.    * BP_ISMAPPED will never be false for character devices,
  762.    * only block devices.
  763.    */
  764.    if(!BP_ISMAPPED(bp)) {
  765.       cmn_err(CE_WARN,
  766.          "gbd driver can't handle unmapped buffers");
  767.       bp->b_flags |= B_ERROR;
  768.       iodone(bp);
  769.       return;
  770.    }
  771.  
  772.    gbd_curbp[unit] = bp;
  773.    /*
  774.    * Initialize the current transfer address and count.
  775.    * The first transfer should finish the rest of the
  776.    * page, but do no more than the total byte count.
  777.    */
  778.    gbd_curaddr[unit] = bp->b_dmaaddr;
  779.    gbd_totcount[unit] = bp->b_count;
  780.    gbd_curcount[unit] = NBPC -
  781.       ((unsigned int)gbd_curaddr[unit] & (NBPC-1));
  782.    if (bp->b_count < gbd_curcount[unit])
  783.       gbd_curcount[unit] = bp->b_count;
  784.    /* Tell the device starting physical address, count,
  785.    * and direction */
  786.    gbd_device[unit]->startaddr = kvtophys(gbd_curaddr[unit]);
  787.    gbd_device[unit]->count = gbd_curcount[unit];
  788.    if (bp->b_flags & B_READ) == 0)
  789.       gbd_device[unit]->direction = GBD_WRITE;
  790.    else
  791.       gbd_device[unit]->direction = GBD_READ;
  792.    gbd_device[unit]->command = GBD_GO;   /* start DMA */
  793.  
  794.    /* and return; upper layers of kernel wait for iodone(bp) */
  795. }
  796.  
  797.  
  798.  
  799. Device Driver Example
  800.  
  801. On the following pages is the complete driver code for the mythical "gbd" 
  802. GIO device. Note that it includes strategy routines for devices that have 
  803. hardware support for scatter-gather as well as for those devices that have no 
  804. hardware scatter-gather support.
  805.  
  806. Normally defines for a driver are kept in a separate header file. In the case of 
  807. this mythical device, these defines would be found in gbd.h. For this 
  808. example, these defines are contained in the driver source file itself.
  809.  
  810. To compile this example, the following command line would be used 
  811. assuming the source code is found in a file named gbd.c:
  812.  
  813. For an Indigo (R3000):        
  814.  
  815.         cc -DIP12 -DR3000 -cckr -c gbd.c
  816.  
  817. For an Indigo (R4000):
  818.  
  819.         cc -DIP20 -DR4000 -cckr -c gbd.c
  820.  
  821. For an Indigo2 (R4000):        
  822.  
  823.         cc -DIP20 -DR4000 -cckr -c gbd.c
  824.  
  825. /* Source for a mythical GIO board device; it can be compiled
  826.  * for devices that support DMA (with or without scatter-
  827.  * gather support), or for PIO mode only. This version is
  828.  * designed for IRIX 5.1 or later.
  829.  * Dave Olson, 5/93
  830.  */
  831.  
  832.  
  833.  
  834. /* NOTE: compile with cc -coff; kernels can't be in
  835.  * ELF format for now */
  836.  
  837. /* defines for compilation; would normally be passed on 
  838. compilation
  839.  * line via Makefile */
  840. #define _K32U32   1
  841. #define _KERNEL   1
  842.  
  843. #define IP20   1   /* define cpu type */
  844.  
  845. #if IP20 || IP22
  846. #define R4000   1
  847. #elif IP12
  848. #define R3000   1
  849. #endif
  850.  
  851. /* end of `normal' compilation definitions */
  852.  
  853. /* The following definitions choose between PIO vs DMA
  854.  * supporting boards, and if DMA is supported, whether
  855.  * hardware scatter-gather is supported. */
  856. #define GBD_NODMA 0   /* non-zero for PIO version of driver */
  857. #define GBD_NUM_DMA_PGS 4 /* 0 for no hardware scatter-gather 
  858.                           * support, else number of pages of
  859.                           * scatter-gather supported per
  860.                           * request */
  861.  
  862. #include <sys/param.h>
  863. #include <sys/systm.h>
  864. #include <sys/cpu.h>
  865. #include <sys/buf.h>
  866. #include <sys/cred.h>
  867. #include <sys/uio.h>
  868. #include <sys/ddi.h>
  869. #include <sys/errno.h>
  870. #include <sys/cmn_err.h>
  871. #include <sys/edt.h>
  872.  
  873.    /* NOTE: This sample driver ignores the possiblity that
  874.     * the board might be busy handling some earlier request.
  875.     * Any real device must deal with that possiblity, of
  876.     * course, before changing the board registers.
  877.     */
  878.  
  879. /* these defines and structures would normally be in
  880.  * a separate header file */
  881.  
  882. #define GBD_BOARD_ID   0x75
  883. #define GBD_MASK   0xff  /* Use 0xff if using only first byte
  884.                           * of ID word; use 0xffff if using
  885.                           * whole ID word.
  886.                           */
  887.  
  888. #define GBD_MEMSIZE 0x8000
  889.  
  890. /* command definitions */
  891. #define GBD_GO 1
  892.  
  893. /* state definitions */
  894. #define GBD_SLEEPING 1
  895. #define GBD_DONE 2
  896.  
  897.  
  898.  
  899. /* direction of DMA definitions */
  900. #define GBD_READ 0
  901. #define GBD_WRITE 1
  902.  
  903. /* status defines */
  904. #define   GBD_INTR_PEND   0x80
  905.  
  906. /* "gbd" is device prefix; also in master.d/xxx file */
  907.  
  908. /* devices interface to the board */
  909. struct gbd_device {
  910.    int command;
  911.    int count;
  912.    int direction;
  913.    off_t offset;
  914.    unsigned *sgregisters; /* if scatter-gather supported */
  915.    caddr_t startaddr;   /* if no scatter-gather on board */
  916.    unsigned status;   /* errors, interrupt pending, etc. */
  917. };
  918.  
  919. /* These are used for no scatter-gather case only, and assume
  920.  * (since they aren't protected!) that the driver is
  921.  * completely single threaded. */
  922. struct buf   *gbd_curbp[2];      /* current buffer */
  923. caddr_t      gbd_curaddr[2];    /* current address to transfer */
  924. int          gbd_curcount[2];
  925. int          gbd_totcount[2];
  926.  
  927. /* pointer to on-board registers */
  928. volatile struct gbd_device *gbd_device[2];
  929.  
  930. char *gbd_memory[2];   /* pointer to on-board memory */
  931.  
  932. static int gbd_state[2];   /* flag for transfer state
  933.                              * (PIO driver) */
  934.  
  935. void gbdintr(int, struct eframe_s *);
  936. extern int splgio1(void);
  937.  
  938. /* equipped device table initialization routine.  The edt
  939.  * structure is defined in edt.h.
  940.  */
  941. void
  942. gbdedtinit(struct edt *e)
  943. {
  944.    int slot, val;
  945.  
  946.    /* Check to see if the device is present */
  947.    if(badaddr_val(e->e_base, sizeof(int), &val) ||
  948.          (val && GBD_MASK) != GBD_BOARD_ID) {
  949.       if (showconfig)
  950.          cmn_err (CE_CONT,
  951.             "gbdedtinit: board not installed.");
  952.          return;
  953.    }
  954.  
  955.  
  956.    /* figure out slot from base on VECTOR line in
  957.     * system file */
  958.    if(e->e_base == (caddr_t)0xBF400000)
  959.       slot = GIO_SLOT_0;
  960.    else if(e->e_base == (caddr_t)0xBF600000)
  961.       slot = GIO_SLOT_1;
  962.    else {
  963.       cmn_err (CE_NOTE,
  964.       "ERROR from edtinit: Bad base address %x\n", e->e_base);
  965.       return;
  966.    }
  967.  
  968. #if IP12      /* For Indigo R3000, set up board as a
  969.                  * realtime bus master.
  970.                */
  971.  
  972.    setgioconfig(slot,0);
  973.  
  974. #endif
  975.  
  976. #if IP20      /* For Indigo R4000, set up board as a
  977.                  * realtime bus master.
  978.                  */
  979.  
  980.    setgioconfig(slot,GIO64_ARB_EXP0_RT | GIO64_ARB_EXP0_MST);
  981.  
  982. #endif
  983.  
  984. #if IP22      /* for Indigo2, set up board as a pipelined,
  985.                  * realtime bus master */
  986.  
  987.    setgioconfig(slot,GIO64_ARB_EXP0_RT | GIO64_ARB_EXP0_MST);
  988.  
  989.  
  990.  
  991. #endif
  992.  
  993.  
  994.  
  995.    /* Save the device addresses, because
  996.     * they won't be available later. */
  997.  
  998.    gbd_device[slot == GIO_SLOT_0 ? 0 : 1] =
  999.             (struct gbd_device *)e->e_base;
  1000.    gbd_memory[slot == GIO_SLOT_0 ? 0 : 1] =
  1001.             (char *)e->e_base2;
  1002.    setgiovector(GIO_INTERRUPT_1,slot,gbdintr,0);
  1003. }
  1004.  
  1005. /* minor number used to indicate which slot; open does nothing
  1006.  * but check that board is present. */
  1007. /* ARGSUSED */
  1008. gbdopen(dev_t *devp, int flag, int otyp, cred_t *crp)
  1009. {
  1010.    if(!gbd_device[geteminor(*devp)&1])
  1011.       return ENXIO;   /* board not present */
  1012.    return 0;   /* OK */
  1013. }
  1014.  
  1015. /* ARGSUSED */
  1016. gbdclose(dev_t dev, int flag, int otyp, cred_t *crp)
  1017. {
  1018.    return 0;   /* nothing to do */
  1019. }
  1020.  
  1021. #ifdef GBD_NODMA
  1022.  
  1023. /* device write routine entry point (for character devices) 
  1024.  */
  1025. int
  1026. gbdwrite(dev_t dev, uio_t *uio)
  1027. {
  1028.    int unit = geteminor(dev)&1;
  1029.    int size, err=0, s;
  1030.  
  1031.    /* while there is data to transfer */
  1032.    while((size=uio->uio_resid) > 0) {
  1033.  
  1034.       /* Transfer no more than GBD_MEMSIZE bytes
  1035.        * to the device */
  1036.       size = size < GBD_MEMSIZE ? size : GBD_MEMSIZE;
  1037.  
  1038.       /* decrements count and updates uio fields, 
  1039.        * and copies data */
  1040.       if(err=uiomove(gbd_memory[unit], size, UIO_WRITE, uio))
  1041.          break;
  1042.  
  1043.       /* prevent interrupts until we sleep */
  1044.       s = splgio1();
  1045.  
  1046.       /* Transfer is complete; start output */
  1047.       gbd_device[unit]->count = size;
  1048.       gbd_device[unit]->command = GBD_GO;
  1049.       gbd_state[unit] = GBD_SLEEPING;
  1050.       while (gbd_state[unit] != GBD_DONE) {
  1051.          sleep(&gbd_state[unit], PRIBIO);
  1052.       }
  1053.       /* restore the process level after waking up */
  1054.       splx(s);
  1055.    }
  1056.    return err;
  1057. }
  1058.  
  1059.  
  1060. /* interrupt routine for PIO only board, just wake up
  1061.  * upper half of driver
  1062.  */
  1063. /* ARGSUSED1 */
  1064. void
  1065. gbdintr(int unit, struct eframe_s *ef)
  1066. {
  1067.    /* Read your board's registers to determine if there are
  1068.     * any errors or interrupts pending. If no interrupts 
  1069.     * are pending, return without doing anything.
  1070.     */
  1071.    if(!gbd_device[unit]->status & GBD_INTR_PEND)
  1072.       return;
  1073.  
  1074.    if (gbd_state[unit] == GBD_SLEEPING) {
  1075.       /* Output is complete; wake up top half
  1076.        * of driver, if it is waiting. */
  1077.       gbd_state[unit] = GBD_DONE;
  1078.       wakeup(&gbd_state[unit]);
  1079.    }
  1080.  
  1081.    /* Do anything else to board to tell it we are done
  1082.     * with transfer and interrupt here. */
  1083. }
  1084.  
  1085. #else   /* DMA version of driver */
  1086.  
  1087. void gbd_strategy(struct buf *);
  1088.  
  1089. /* device write routine entry point (for character devices).
  1090.  * Does nothing but call uiophysio to setup passing a pointer
  1091.  * to the gbd_strategy routine, which does most of the work.
  1092. */
  1093. int
  1094. gbdwrite(dev_t dev, uio_t *uiop)
  1095. {
  1096.    return uiophysio((int (*)())gbd_strategy, 0, dev, B_WRITE, uiop);
  1097. }
  1098.  
  1099. #if GBD_NUM_DMA_PGS > 0
  1100.  
  1101. /* Actual device setup for DMA, etc., if your board has
  1102.  * hardware scatter-gather DMA support.
  1103.  * Called from the gbdwrite() routine via physio().
  1104.  */
  1105. void
  1106. gbd_strategy(struct buf *bp)
  1107. {
  1108.    int unit = geteminor(bp->b_dev)&1;
  1109.    int npages;
  1110.    volatile unsigned *sgregisters;
  1111.    int i, v_addr;
  1112.  
  1113.    /* Get address of the scatter-gather registers */
  1114.     *sgregisters = gbd_device[unit]->sgregisters;
  1115.  
  1116.    /* Get the kernel virtual address of the data; note
  1117.     * b_dmaaddr may be NULL if the BP_ISMAPPED(bp) macro
  1118.     * indicates false; in that case, the field bp->b_pages
  1119.     * is a pointer to a linked list of pfdat structure
  1120.     * pointers; that saves creating a virtual mapping and
  1121.     * then decoding that mapping back to physical addresses.
  1122.     * BP_ISMAPPED will never be false for character devices,
  1123.     * only block devices.
  1124.     */
  1125.     if(!BP_ISMAPPED(bp)) {
  1126.       cmn_err(CE_WARN,
  1127.          "gbd driver can't handle unmapped buffers");
  1128.       bp->b_flags |= B_ERROR;
  1129.       iodone(bp);
  1130.       return;
  1131.    }
  1132.  
  1133.    v_addr = bp->b_dmaaddr;
  1134.  
  1135.    /* Compute number of pages received.
  1136.     * The dma_len field provides the number of pages to
  1137.     * map. Note that this may be larger than the actual
  1138.     * number of bytes involved in the transfer. This is
  1139.     * because the transfer may cross page boundaries,
  1140.     * requiring an extra page to be mapped. Limit to
  1141.     * number of scatter-gather registers on board.
  1142.     * Note that this sample driver doesn't handle the
  1143.     * case of requests > than # of registers!
  1144.     */
  1145.    npages = numpages (v_addr, bp->b_dmalen);
  1146.    /*
  1147.     * Provide the beginning byte offset and count to the
  1148.     * device.
  1149.     */
  1150.    gbd_device[unit]->offset =
  1151.          (unsigned int)bp->b_dmaaddr & (NBPC-1);
  1152.    if(npages > GBD_NUM_DMA_PGS) {
  1153.       npages = GBD_NUM_DMA_PGS;
  1154.       cmn_err(CE_WARN,
  1155.           "request too large, only %d pages max", npages);
  1156.       if(gbd_device[unit]->offset)
  1157.          gbd_device[unit]->count = NBPC -
  1158.              gbd_device[unit]->offset + (npages-1)*NBPC;
  1159.       else
  1160.          gbd_device[unit]->count = npages*NBPC;
  1161.       bp->b_resid = bp->b_count - gbd_device[unit]->count;
  1162.    }
  1163.    else
  1164.       gbd_device[unit]->count = bp->b_count;
  1165.  
  1166.    /* Translate the virtual address of each page to a
  1167.     * physical page number and load it into the next
  1168.     * scatter-gather register. The btoct(D3X) macro
  1169.     * converts the byte value to a page value after
  1170.     * rounding down the byte value to a full page.
  1171.     */
  1172.     for (i = 0; i < npages; i++) {
  1173.       *sgregisters++ = btoct(kvtophys(v_addr));
  1174.  
  1175.       /* Get the next virtual address to translate.
  1176.        * (NBPC is a symbolic constant for the page
  1177.        * size in bytes)
  1178.        */
  1179.  
  1180.       v_addr += NBPC;
  1181.    }
  1182.  
  1183.    if ((bp->b_flags & B_READ) == 0)
  1184.       gbd_device[unit]->direction = GBD_WRITE;
  1185.    else
  1186.       gbd_device[unit]->direction = GBD_READ;
  1187.    gbd_device[unit]->command = GBD_GO;   /* start DMA */
  1188.  
  1189.    /* and return; upper layers of kernel wait for iodone(bp) */
  1190. }
  1191.  
  1192.  
  1193. /* not much to do in this interrupt routine, since we are
  1194.  * assuming for this driver that we can never have to do
  1195.  * multiple DMA's to handle the number of bytes requested...
  1196.  */
  1197. void
  1198. gbdintr(int unit)
  1199. {
  1200.    int error;
  1201.  
  1202.    /* Read your board's registers to determine if
  1203.     * there are any errors or interrupts pending.
  1204.     * If no interrupts are pending, return without
  1205.     * doing anything.
  1206.     */
  1207.  
  1208.    if(!gbd_device[unit]->status & GBD_INTR_PEND)
  1209.       return;
  1210.  
  1211.    if(error)
  1212.       bp->b_flags |= B_ERROR;
  1213.  
  1214.    iodone(bp);   /* we are done, tell upper layers */
  1215.  
  1216.    /* do anything else to board to tell it we are done
  1217.     * with transfer and interrupt here */
  1218. }
  1219.  
  1220. #else /*  GBD_NUM_DMA_PGS == 0; no hardware
  1221.        *  scatter-gather support */
  1222.  
  1223. /* Actual device setup for DMA, etc., if your board
  1224.  * does NOT have hardware scatter-gather DMA support.
  1225.  * Called from the gbdwrite() routine via physio().
  1226.  */
  1227. void
  1228. gbd_strategy(struct buf *bp)
  1229. {
  1230.    int unit = geteminor(bp->b_dev)&1;
  1231.  
  1232.    /* any checking for initial state here. */
  1233.  
  1234.    /* Get the kernel virtual address of the data; note
  1235.     * b_dmaaddr may be NULL if the  BP_ISMAPPED(bp) macro
  1236.     * indicates false; in that case, the field bp->b_pages
  1237.     * is a pointer to a linked list of pfdat structure
  1238.     * pointers; that saves creating a virtual mapping and
  1239.     * then decoding that mapping back to physical addresses.
  1240.     * BP_ISMAPPED will never be false for character devices,
  1241.     * only block devices.
  1242.     */
  1243.     if(!BP_ISMAPPED(bp)) {
  1244.       cmn_err(CE_WARN,
  1245.          "gbd driver can't handle unmapped buffers");
  1246.       bp->b_flags |= B_ERROR;
  1247.       iodone(bp);
  1248.       return;
  1249.    }
  1250.  
  1251.    gbd_curbp[unit] = bp;
  1252.    /*
  1253.     * Initialize the current transfer address and count.
  1254.     * The first transfer should finish the rest of the
  1255.     * page, but do no more than the total byte count.
  1256.     */
  1257.    gbd_curaddr[unit] = bp->b_dmaaddr;
  1258.    gbd_totcount[unit] = bp->b_count;
  1259.    gbd_curcount[unit] = NBPC -
  1260.       ((unsigned int)gbd_curaddr[unit] & (NBPC-1));
  1261.    if (bp->b_count < gbd_curcount[unit])
  1262.       gbd_curcount[unit] = bp->b_count;
  1263.    /* Tell the device starting physical address, count,
  1264.     * and direction */
  1265.    gbd_device[unit]->startaddr = kvtophys(gbd_curaddr[unit]);
  1266.    gbd_device[unit]->count = gbd_curcount[unit];
  1267.    if (bp->b_flags & B_READ) == 0)
  1268.       gbd_device[unit]->direction = GBD_WRITE;
  1269.    else
  1270.       gbd_device[unit]->direction = GBD_READ;
  1271.    gbd_device[unit]->command = GBD_GO;   /* start DMA */
  1272.  
  1273.    /* and return; upper layers of kernel wait for iodone(bp) */
  1274. }
  1275.  
  1276.  
  1277. /* more complicated interrupt routine, not necessarily because
  1278.  * board has DMA, but more typical of boards that do have
  1279.  * DMA, since they are typically more complicated.
  1280.  * Also more typical of devices that support block i/o, as
  1281.  * opposed to character i/o.
  1282.  */
  1283. void
  1284. gbdintr(int unit)
  1285. {
  1286.    int error;
  1287.    register struct buf *bp = gbd_curbp[unit];
  1288.  
  1289.    /* read your board's registers to determine if
  1290.     * there are any errors or interrupts pending.
  1291.     * If no interrupts are pending, return without
  1292.     * doing anything.
  1293.     */
  1294.    if(!gbd_device[unit]->status & GBD_INTR_PEND)
  1295.       return;
  1296.  
  1297.    if(error) {
  1298.       bp->b_flags |= B_ERROR;
  1299.       iodone(bp);   /* we are done, tell upper layers */
  1300.    }
  1301.    else {
  1302.       /* On successful transfer of last chunk, continue
  1303.        * if necessary */
  1304.       gbd_curaddr[unit] += gbd_curcount[unit];
  1305.       gbd_totcount[unit] -= gbd_curcount[unit];
  1306.       if(gbd_totcount[unit] <= 0)
  1307.          iodone(bp);
  1308.             /* we are done, tell upper layers */
  1309.       else {
  1310.       /* else more to do, reprogram board and
  1311.        * start next dma */
  1312.       gbd_curcount[unit] =
  1313.          (gbd_totcount[unit] < NBPC
  1314.                ? gbd_totcount[unit] : NBPC);
  1315.       gbd_device[unit]->startaddr =
  1316.                kvtophys(gbd_curaddr[unit]);
  1317.       gbd_device[unit]->count = gbd_curcount[unit];
  1318.       if (bp->b_flags & B_READ) == 0)
  1319.          gbd_device[unit]->direction = GBD_WRITE;
  1320.       else
  1321.          gbd_device[unit]->direction = GBD_READ;
  1322.       gbd_device[unit]->command = GBD_GO;
  1323.                /* start next DMA */
  1324.       }
  1325.    }
  1326.  
  1327.    /* Do anything else to board to tell it we are done
  1328.     * with transfer and interrupt here. */
  1329. }
  1330. #endif /*  GBD_NUM_DMA_PGS */
  1331.  
  1332. #endif /* GBD_NODMA */
  1333.